- 12.8. Distribuição de DF-e [18-06-22]
12.8.1. Consulta DF-e emitidos para um interessado [12-08-22] - 12.8. Distribuição de DF-e [18-06-22]
« Anterior - 12.8.2. Consulta DF-e por NSU [12-08-22]
Próximo »
12.8.1. Consulta DF-e emitidos para um interessado [12-08-22]
Consultar as informações resumidas e documentos interesse da consulente a partir do NSU informado no parâmetro ultNSURecebido.
DICA
O uso adequado deste WS é suficiente para a obtenção de todos os Documentos Fiscais eletrônicos - DF-e que são disponibilizados pelo serviço inexistindo necessidade de uso do WS consulta por chave de acesso da NF-e (consChNFe) e do WS consulta por NSU (consNSU).
Assinatura
string distNSU(string siglaWS, int tipoAmbiente, string nomeCertificado, string versao, out string msgDados, out string msgRetWS, out int cStat, out string msgResultado, string CNPJ, string cUF, string ultNSURecebido, out string verAplic, out string dhResp, out string ultNSU, out string maxNSU, out int qtdeDocto, string proxy, string usuario, string senha, string licenca);
Descrição:
Consulta as informações resumidas e DF-e existentes para o interessesado a partir do NSU informado no parâmetro ultNSURecebido, o Web Service retorna até 50 informações resumidas e/ou documentos fiscais a partir do ultNSURecebido consultado.
ALERTA SOBRE O USO DA FUNCIONALIDADE
LIMITAÇÃO DE USO APÓS NT 2014.002 V1.12 de 09/03/2022
A versão 1.12 da NT 2014.002 implementou regras de USO INDEVIDO dos serviços de download de NF-e.
Veja o AVISO sobre a Atualização das regras de Uso do Web Service NFeDistribuiçãoDFe - NT 2014.002 para maiores detalhes das alterações.
Quantidade máxima de consulta por hora
Quando inexistirem mais documentos disponíveis (cStat=137 ou ultNSU = maxNSU), a aplicação deve aguardar um hora para retomar a consulta. A persistência na consulta após receber o cStat=137 ou ultNSU = maxNSU provocará a rejeição "656 - Rejeicao: Consumo Indevido. Deve ser aguardado 1 hora para efetuar nova solicitação caso não existam mais documentos a serem pesquisados. Tente após 1 hora.
Consulta de NSU deve ser sequencial
A consulta deve ser iniciada a partir de um NSU existente (pode ser informado zero quando não souber o primeiro NSU existente) e as consultas subsequentes devem ser a partir do ultNSU retornado até alcançar a condição ultNSU = maxNSU, a quebra da sequência de consulta provocará a rejeição "656 - Rejeicao: Consumo Indevido. Deve ser utilizado o ultNSU nas solicitacoes subsequentes. Tente apos 1 hora".
CONSUMO INDEVIDO - consequências
A ocorrência da rejeição "656 - Rejeicao: Consumo indevido ... " provoca o BLOQUEIO do CNPJ/CPF do interessado por uma hora, impedindo a realização de consultas neste período.
O desbloqueio é automático, mas é necessário aguardar o intervalo de tempo de uma hora, toda consulta realizada durante o período de bloqueio provoca o reínicio da contagem do tempo de bloqueio e pode provocar um loop infinito de consumo indevido no caso do usuário não aguardar o decurso do prazo de uma hora para realizar uma nova consulta.
IMPLEMENTAÇÃO
DICA DE IMPLEMENTAÇÃO
Se o ultNSU for menor que o maxNSU, o interesssado deve repetir a consulta atualizando o ultNSURecebido com o ultNSU devolvido pelo WS.
A forma adequada de implementar a consulta de documentos destinados é através de um serviço ou aplicativo que faz a consulta do WS a cada hora.
É necessário armazenar o último NSU obtido na consulta anterior, a aplicação deve efetuar a consulta do serviço enquanto o último NSU for menor que NSU máximo, ambas as informações são devolvidas pelo serviço.
ultNSURecebido = ultNSUanterior ultNSu = 0 maxNSU = 99999999 cStat = 0 txtRetorno ="" enquanto ultNSU < maxNSU ' IMPORTANTE, se ultNSU = maxNSU ==> FINALIZAR LOOP, POIS POIS NÃO EXISTE MAIS NSU, ' continuar a chamada vai provocar CONSUMO INDEVIDO. txtRetorno = txtRetorno + distNSU(...., cStat, ..., ultNSURecebido, ultNSU, ... maxNSU, ...) se cStat <> 656 ultNSURecebido = ultNSU ' não atualizar quando ocorre consumo indevido, pois os retornos são zerados fim_se fim_enquanto ' ultNSU < maxNSU ' tratar txtRetorno se ultNSURecebido > ultNSUAnterior ' significa que existem novos NSU ' tratar TXT de retorno da chamada, que retorna uma linha para cada NSU ' cada linha tem 3 informações separados por PIPE(|): NSU|tipo documento|XML Tratar TXT para extrair uma linha de cada vez, veja exemplo em VB 6.0 e Delphi que existe abaixo. ' O tratamento deve extrair o NSU, tipoSchemaXML e XML ' ' É recomendavel criar uma tabela para manter o NSU, tipoSchemaXML e XML, facilita a identificação do NSU ' recebidos e no caso de precisar processar novamente ' inserir NSU, tipoSchemaXML e XML na tabela ' Quando o ator for o destinatário, é necessário fazer a manifestação do destinatário para liberar o ' XML completo da NF-e. ' se tipoSchemaXML = "resNFe_v1.01.xsd" ' extrarir chave de acesso da NF-e do XML ' fazer ciência da operação da NF-e para liberar o XML completo da NF-e, este XML deve aparecer ' nas próximas chamadas do distNSU fazer a ciência da operação do resumo da NF-e fim_se ' tipoSchemaXML ' tratar os demais tipoSchemaXML, os mais importantes são "procNFe_v4.00.xsd" => XML completo e o ' "resEvento_v1.01.xsd" que pode trazer informação de cancelamento da NF-e, CC-e, etc. fim_se ' ultNSURecebido > ultNSUAnterior<br>
Parâmetros:
| nome | tipo | fluxo | descrição |
|---|---|---|---|
| siglaWS | string | entrada | informar "AN" - o WS do Ambiente Nacional (AN) atende destinatário de qualquer UF. |
| tipoAmbiente | inteiro | entrada | informar o código do ambiente desejado: 1- produção ou 2-homologação |
| NomeCertificado | string | entrada | informar o certificado digital que será utilizado para assinatura: 1. informar o assunto do certificado digital que deve existir no repositório MY do current user, ex.: "CN=NFe - Associacao NF-e:99999090910270, C=BR, L=PORTO ALEGRE, O=Teste Projeto NFe RS, OU=Teste Projeto NFe RS, S=RS". 2. informar: ARQUIVO | [nome do arquivo pfx com caminho completo] | [senha do arquivo] para uso do certificado digital em arquivo pfx, ex.: "ARQUIVO|c:\certificado.pfx|senha". 3. informar: CERTIFICADO | [string base64 do arquivo pfx] | [senha do arquivo] no parâmetro NomeCertificado para passar uma string contendo um certificado digital em base64, ex.:"CERTIFICADO|MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy|senha". (novas opções) |
| versao | string | entrada | informar a versão da mensagem do WS: 4.00 |
| msgDados | string | saída | retorna a mensagem XML enviada para o WS |
| msgRetWS | string | saída | retorna a mensagem XML de resposta do WS |
| cStat | inteiro | saída | retorna o resultado da chamada do WS |
| msgResultado | string | saída | retorna a literal do resultado da chamada do WS |
| CNPJ | string | entrada | informar o CNPJ ou CPF do ator que se deseja consultar os documentos fiscais. [26-08-18] |
| cUF | string | entrada | informar o cUF |
| ultNSURecebido | string | entrada | informar o NSU a partir do qual deseja realizar a consulta. |
| verAplic | string | saída | retorna a versão da aplicação do Web Service. |
| dhResp | string | saída | retorna a Data e hora da mensagem de Resposta. |
| ultNSU | string | saída | retorna o Último NSU pesquisado na Web Service. Se exisitrem mais NSU (maxNSU > ultNSU), o solicitante pode continuar a consulta a partir deste NSU para obter novos resultados. |
| maxNSU | string | saída | retorna Maior NSU existente no Ambiente Nacional para o CNPJ/CPF informado. |
| qtdeDocto | int | saída | retorna a quantidade de documentos devolvidos pelo WS. |
| proxy | string | entrada | informar 'http://proxyserver:port' quando existir uso de proxy no ambiente. verificar com o cliente qual é o endereço do servidor proxy e a porta https, a porta padrão do https é 443, assim teríamos algo do tipo 'http://192.168.15.1:443' |
| usuario | string | entrada | informar o usuário para autenticação no proxy, se necessário |
| senha | string | entrada | informar a senha de autenticação no proxy, se necessário |
| licenca | string | entrada | informar a chave da licenca de uso ou registro, esta funcionalidade pode ser utilizada sem qualquer restrição no ambiente de homologação. O uso em ambiente de produção requer o licenciamento, para maiores detalhes veja as condições de uso |
Preenchimento da siglaWS
AN - O WS do Ambiente Nacional (AN) atende qualquer UF.
Preenchimento do nomeCertificado
informar o Nome do titular (campo Assunto) do certificado digital a ser utilizado na conexão SSL, formas possíveis:
1. uso de certificado digital existente no repositório MY do CSP do usuário corrente (currentuser)
É a forma de mais comum de uso, cabe ressaltar que é a única forma de uso de certificado digital do tipo A3 que a DLL oferece.
O usuário deve passar como parâmetro o campo assunto do certificado no parâmetro NomeCertificado para que a DLL localize um certificado digital com mesmo assunto no repositório MY do currentuser do equipamento.
Esta forma de uso requer a prévia instalação do certificado digital na conta do usuário do Windows (logon) que irá utilizar o certificado digital.2. uso de certificado digital em arquivo no formato pfx
Permite o de uso de certificado digital em arquivo formato pfx.
O caminho da localização (path) do arquivo pfx deve ser passado para a DLL no formato: ARQUIVO | [nome do arquivo pfx com caminho completo] | [senha do arquivo] no parâmetro NomeCertificado, ex.: "ARQUIVO|c:\certificado.pfx|senha".
Esta opção só funciona com certificado digital do tipo A1.3. uso de certificado digital em string base64
Permite uso o arquivo do certificado digital em formato pfx convertido em uma string base64. O certificado digital em string base64 deve ser passado para a DLL no formato: CERTIFICADO | [string base64 do arquivo pfx] | [senha do arquivo] no parâmetro NomeCertificado, ex.: "CERTIFICADO|MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy|senha".
Esta opção só funciona com certificado digital do tipo A1. É uma opção de uso que oferece maior versatilidade, pois permite o armazenamento do certificado digital em banco de dados na aplicação. É a forma mais indicada para uso em ASP.NET.
Retorno:
A chamada devolve uma string com o resumo ou XML do documento consultado separados por quebra de linha.
O retorno é um TXT que tem uma linha para cada documento.
Cada linha tem 3 informações separadas por pipe (|):
NSU|tipo documento|XML
000000000004616|resNFe_v1.01.xsd |<resNFe versao="(...)>
000000000004617|resNFe_v1.01.xsd |<resNFe versao="(...)>
000000000004618|procNFe_v4.00.xsd |<nfeProc versao="(...)>
A parte inicial do texto é sempre posicional:
| posições | conteúdo |
|---|---|
| 1 a 15 | NSU |
| 17 a 52 | tipo do documento (schema XML) |
| 54 a ... | XML do documento |
Exemplo de tratamento do TXT devolvido:
Visual Basic 6.0
Dim TXT As String Dim linhas As Variant Dim txtNSU As String Dim txtSchema As String Dim txtXML As String Dim i As Integer TXT = "" ' ' TXT que retorna do distNSU ' ' +---------+-------------------------------+ ' |posições | conteúdo | ' +---------+-------------------------------+ ' | 1 a 15 | NSU | ' | 17 a 52 | tipo do documento (schema XML)| ' | 54 a ...| XML do documento | ' +---------+-------------------------------+ ' ' EXEMPLO DE TXT ' ' ------NSU------+----------schema XML---------------+-------XML---- ' 0........1......1..2.........3.........4.........5..5......6...... ' 123456789012345678901234567890123456789012345678901234567890123456 ' 000000000000364|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe> ' 000000000000365|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe> ' 000000000000366|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc> ' TXT = TXT + "000000000000364|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe>" + Chr(13) TXT = TXT + "000000000000365|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe>" + Chr(13) TXT = TXT + "000000000000366|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc>" + Chr(13) TXT = TXT + "000000000000367|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc>" + Chr(13) TXT = TXT + "000000000000368|resEvento_v1.01.xsd |<resEvento>...</resEvento>" + Chr(13) ' ' quebra o TXT no vetor linha, o delimitador da linha é caracter ASC=13 ' linhas = Split(TXT, Chr(13)) ' ' laço para extrair o NSU, schemaXML e XML ' For i = 0 To UBound(linhas) - 1 ' para OPTION BASE 0 txtNSU = Left(linhas(i), 15) txtSchema = Trim(Mid(linhas(i), 17, 35)) txtXML = Right(linhas(i), Len(linhas(i)) - 52) MsgBox "item[" + Str(i) + "]" + Chr(13) + "NSU : " + txtNSU + Chr(13) + "Schema: " + txtSchema + Chr(13) + "XML : " + txtXML Next
Delphi
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls; type TForm1 = class(TForm) Button1: TButton; procedure Button1Click(Sender: TObject); private { Private declarations } public { Public declarations } end; var Form1: TForm1; implementation {$R *.dfm} procedure TForm1.Button1Click(Sender: TObject); var i: integer; linha:TStringList; txtNFe: string; txtNSU: string; txtSchema: string; txtXML : string; begin txtNFe := ''; // // TXT que retorna do distNSU // // +---------+-------------------------------+ // |posições | conteúdo | // +---------+-------------------------------+ // | 1 a 15 | NSU | // | 17 a 52 | tipo do documento (schema XML)| // | 54 a ...| XML do documento | // +---------+-------------------------------+ // // EXEMPLO DE TXT // // ------NSU------+----------schema XML---------------+-------XML---- // 0........1......1..2.........3.........4.........5..5......6...... // 123456789012345678901234567890123456789012345678901234567890123456 // 000000000000364|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe> // 000000000000365|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe> // 000000000000366|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc> // txtNFe := txtNFe + '000000000000364|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe>' + Chr(13); txtNFe := txtNFe + '000000000000365|resNFe_v1.01.xsd |<resNFe><chNFe>...</chNFe>...<cSitNFe>1</cSitNFe></resNFe>' + Chr(13); txtNFe := txtNFe + '000000000000366|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc>' + Chr(13); txtNFe := txtNFe + '000000000000367|procNFe_v4.00.xsd |<nfeProc><NFe>...</NFe><protNFe>...</protNFe></nfeProc>' + Chr(13); txtNFe := txtNFe + '000000000000368|resEvento_v1.01.xsd |<resEvento>...</resEvento>' + Chr(13); // // quebra o TXT no vetor linha, o delimitador da linha é caracter ASC=13 // linha := TStringList.Create; linha.Delimiter := chr(13); linha.Text := txtNFe; // // laço para extrair o NSU, schemaXML e XML // for i:=0 to linha.Count - 1 do begin txtNSU := copy(linha[i],1,15); // posições: 1 a 15 - NSU txtSchema := copy(linha[i],17,35); // posições: 17 a 51 - SchemaXML txtXML := copy(linha[i],53,length(linha[i])-52); // posições: 53 a fim - XML MessageDlg('linha: ' + inttostr(i) + Chr(13)+'NSU: ' + txtNSU +Chr(13)+'Schema: ' + txtSchema +Chr(13)+'XML: ' + txtXML, mtInformation, [mbOk], 0); end; end; end.
- 12.8.1. Consulta DF-e emitidos para um interessado [12-08-22]
12.8. Distribuição de DF-e [18-06-22] - « Anterior
12.8. Distribuição de DF-e [18-06-22] - Próximo »
12.8.2. Consulta DF-e por NSU [12-08-22]